home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / biblio / bibtex / utils / bibsort / bibsort.txt < prev    next >
Text File  |  1992-10-18  |  7KB  |  265 lines
  1.  
  2.  
  3.  
  4. BIBSORT(1)         USER COMMANDS               BIBSORT(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      bibsort - sort a BibTeX bibliography file
  10.  
  11. SYNOPSIS
  12.      bibsort [optional sort(1) switches] < infile >outfile
  13.  
  14. DESCRIPTION
  15.      bibsort filters a BibTeX bibliography, or bibliography frag-
  16.      ment,  on    its standard input, printing on    standard output    a
  17.      sorted bibliography.
  18.  
  19.      Sorting is    by BibTeX tag name, or by @String macro    name, and
  20.      letter case is ignored in the sorting.
  21.  
  22.      If    no command-line    switches are provided for  sort(1),  then
  23.      -f     is  supplied to cause letter case to be ignored.  If you
  24.      also want to remove duplicate entries, you    could specify the
  25.      switches -f -u.
  26.  
  27.      The input stream is conceptually divided  into  four  parts,
  28.      any of which may be absent.
  29.  
  30.       1.  Introductory  material  such  as     comments,   file
  31.           headers,    and edit logs that are ignored by BibTeX.
  32.           No line in this part begins with an at-sign, ``@''.
  33.  
  34.       2.  Preamble material    delineated by ``@Preamble{''  and
  35.           a     matching closing ``}'', intended to be    processed
  36.           by TeX.  Normally, there is only one such    entry  in
  37.           a     bibliography file, although BibTeX, and bibsort,
  38.           permit more than one.
  39.  
  40.       3.  Macro definitions    of the form ``@String{...}''.    A
  41.           single  macro  definition     may span multiple lines,
  42.           and there    are usually several such definitions.
  43.  
  44.       4.  Bibliography  entries  such  as  ``@Article{...}'',
  45.           ``@Book{...}'',  ``@Proceedings{...}'',  and so on.
  46.           For bibsort, any line that  begins  with    an  ``@''
  47.           immediately  followed  by    letters    and digits and an
  48.           open brace is considered to be such an entry.
  49.  
  50.      The order of these    parts is preserved in the output  stream.
  51.      Part  1  will  be    unchanged,  but    parts 2--4 will    be sorted
  52.      within themselves.
  53.  
  54.      The sort key of ``@Preamble'' entries is their initial line,
  55.      of     ``@String''  entries,    the macro name,    and of all BibTeX
  56.      entries, the citation tag between the open    curly  brace  and
  57.      the trailing comma.
  58.  
  59.  
  60.  
  61.  
  62.  
  63. Version    0.00      Last change: 13 October 1992            1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. BIBSORT(1)         USER COMMANDS               BIBSORT(1)
  71.  
  72.  
  73.  
  74.      bibsort will correctly handle UNIX    files with LF line termi-
  75.      nators, as    well as    IBM PC DOS files with CR LF line termina-
  76.      tors; the essential requirement is    that input lines be  del-
  77.      ineated by    LF characters.
  78.  
  79. CAVEATS
  80.      BibTeX has    loose syntactical requirements that  the  current
  81.      simple  implementation of bibsort does not    support.  In par-
  82.      ticular, outer parentheses    may  not  be  used  in    place  of
  83.      braces  following    ``@keyword''  patterns,     nor may there be
  84.      leading or    embedded whitespace.
  85.  
  86.      If    you have such a    file, you can use bibclean(1) to  pretty-
  87.      print it into a form that bibsort can handle successfully.
  88.  
  89.      The user must be aware that sorting a  bibliography  is  not
  90.      without peril, for    at least these reasons:
  91.  
  92.       1.  BibTeX has a requirement that entry tags    given  in
  93.           crossref    =  tag pairs in    a bibliography entry must
  94.           refer to entries defined later,  rather  than  ear-
  95.           lier,  in     the bibliography file.     This regrettable
  96.           implementation limitation    of the current    (pre-1.0)
  97.           BibTeX  prevents arbitrary ordering of entries when
  98.           crossref values are present.
  99.  
  100.       2.  If the BibTeX file contains interspersed commentary
  101.           between  ``@keyword{...}''  entries,  this material
  102.           will be considered part of the preceding entry, and
  103.           will be sorted with it.  Leading commentary is more
  104.           common, and will be moved    elsewhere in the file.
  105.  
  106.           This is normally not  a  problem    for  the  part    1
  107.           material before the ``@Preamble'', since it is kept
  108.           together at the beginning    of the output stream.
  109.  
  110.       3.  Some kinds of bibliography files should be kept  in
  111.           a     different  order than alphabetically by tags.    A
  112.           good example is a    bibliography file with    the  con-
  113.           tents  of    a journal, for which publication order is
  114.           likely more suitable.
  115.  
  116.      While a much more sophisticated  implementation  of  bibsort
  117.      could  deal  with    the  first  point, solving the second one
  118.      requires human intelligence and natural language understand-
  119.      ing that computers    lack.
  120.  
  121.      bibsort uses ASCII    control    characters 001    through     007  for
  122.      temporary    modifications  of  the    input  stream.    If any of
  123.      these are already present in the input, they will be altered
  124.      on     output.  This is unlikely to be a problem, because those
  125.      characters    have neither a printable representation, nor  are
  126.  
  127.  
  128.  
  129. Version    0.00      Last change: 13 October 1992            2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. BIBSORT(1)         USER COMMANDS               BIBSORT(1)
  137.  
  138.  
  139.  
  140.      they  conventionally used to mark line or page boundaries in
  141.      text files.
  142.  
  143. PROGRAMMING NOTES
  144.      Some text editors permit application of an    arbitrary  filter
  145.      command  to a region of text.  For    example, in GNU    emacs(1),
  146.      the   command   C-u    M-x       shell-command-on-region,    or
  147.      equivalently,  C-u     M-|,  can  be    used  to run bibsort on    a
  148.      region of the buffer that is devoid of cross references  and
  149.      other material that cannot    be safely sorted.
  150.  
  151.      Some  implementations  of    BibTeX    editing     support  in  GNU
  152.      emacs(1)  have  a    sort-bibtex-entries command that is func-
  153.      tionally similar to bibsort.  However, the     file  size  that
  154.      can  be  processed    by emacs(1) is limited,    while bibsort can
  155.      be    used on    arbitrarily large  files,  since  it  acts  as    a
  156.      filter,  processing  a  small amount of data at a time.  The
  157.      sort stage    needs the entire data  stream,    but  fortunately,
  158.      the  UNIX sort(1) command is clever enough    to deal    with very
  159.      large inputs.
  160.  
  161.      The current implementation    of bibsort follows the UNIX trad-
  162.      ition  of    combining simple already-available tools.  A six-
  163.      stage pipeline of    egrep(1),  nawk(1),  sort(1),  and  tr(1)
  164.      accomplishes  the    job  in     one  pass with    about 70 lines of
  165.      shell script, 60 lines of which is     a  nawk(1)  program  for
  166.      insertion    of  sort keys.    bibsort    was written and    tested on
  167.      several large bibliographies in a couple of hours.     By  con-
  168.      trast, bibtex(1) is more than 11 000 lines    of code    and docu-
  169.      mentation,    and bibclean(1)    is about 1500 lines long.
  170.  
  171. BUGS
  172.      bibsort may fail on  some    UNIX  systems  if  their  sort(1)
  173.      implementations  cannot  handle very long lines, because for
  174.      sorting purposes, each complete bibliography entry     is  tem-
  175.      porarily  folded  into  a    single    line.  You may be able to
  176.      overcome this problem by adding  a     -znnnnn  switch  to  the
  177.      sort(1)  command (passed via the command line to bibsort) to
  178.      increase the maximum line size to some larger value of nnnnn
  179.      bytes.
  180.  
  181. SEE ALSO
  182.      bibclean(1),   bibtex(1),     egrep(1),   emacs(1),     nawk(1),
  183.      sort(1), tr(1).
  184.  
  185. AUTHOR
  186.      Nelson H. F. Beebe, Ph.D.
  187.      Center for    Scientific Computing
  188.      Department    of Mathematics
  189.      University    of Utah
  190.      Salt Lake City, UT    84112
  191.      Tel: (801)    581-5254
  192.  
  193.  
  194.  
  195. Version    0.00      Last change: 13 October 1992            3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. BIBSORT(1)         USER COMMANDS               BIBSORT(1)
  203.  
  204.  
  205.  
  206.      FAX: (801)    581-4148
  207.      Email: <beebe@math.utah.edu>
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Version    0.00      Last change: 13 October 1992            4
  262.  
  263.  
  264.  
  265.